@database doc/VMMInformer.guide @$VER: VMMInformer.guide V1.1 (29.08.95) @author Torsten Ebeling @Width 72 @Node Main "doc/VMMInformer.guide" @Next "COPYRIGHT" VMMInformer (Graphical statistics program for use with VMM) User's Guide Version 1.1 $Date: 95/08/29 20:41:56 $ written by Torsten Ebeling email: t_ebelin@informatik.uni-kl.de CONTENTS 0. @{" Copyright & Author " Link "COPYRIGHT"} 1. @{" Introduction " Link "INTRODUCTION"} 2. @{" Installation " Link "INSTALLATION"} 3. @{" VMMInformer " Link "VMMInformer"} 4. @{" Preferences file - Syntax " Link "PREFS_SYNTAX"} 5. @{" Error list " Link "ERROR_LIST"} 6. @{" Known bugs " Link "KNOWN_BUGS"} 7. @{" History " Link "HISTORY"} 8. @{" Future plans " Link "PLANS"} 9. @{" Acknowledgments " Link "ACKNOWLEDGMENTS"} @EndNode @Node "COPYRIGHT" "doc/NerveEX.guide/COPYRIGHT" @Next "INTRODUCTION" @Prev "Main" @Toc "Main" @{b}0. COPYRIGHT and AUTHOR@{ub} IMPORTANT NOTICE: This program is copyrighted by Torsten Ebeling, but can be freely distributed, provided that the following rules are respected. - No change is made to the program nor to the accompanying documentation - The package is always distributed in its complete form. - Every form of distribution is allowed and encouraged, but no fee can be charged for this program except for, possibly, the cost of magnetic media and/or disk duplication and shipping. - Inclusion in PD software libraries such as Fish Disks is allowed, provided the fees charged for these disks are comparable with those charged by Fred Fish. - The program cannot be distributed in any commercial product without the written consent of the author. - The author cannot be held liable for the suitability or accuracy of or any damage directly or indirectly caused by the use or misuse of this program. It is the sole responsibility of the user her/him self. By copying, distributing and/or using the program you indicate your acceptance of the above rules. Author: email: t_ebelin@informatik.uni-kl.de snail-mail: Torsten Ebeling Kottenschanze 8 67659 Kaiserslautern Germany @EndNode @Node "INTRODUCTION" "doc/VMMInformer.guide/INTRODUCTION" @Next "INSTALLATION" @Prev "COPYRIGHT" @Toc "Main" @{b}1. INTRODUCTION@{ub} I'm really fed up with writing manuals. This manual will be very short. VMMInformer is a utility which displays information about VMM or the memory situation either as text or graphic. That's it. VMMInformer requires VMM 2.1 or greater to be installed and running on your system if you want to display information about VMM. Otherwise it only shows 'VMM not dependent' information. VMM is a virtual memory manager written by Martin Apel. VMM is available on AMINET and several PD/Shareware Disks or CDs. @EndNode @Node "INSTALLATION" "doc/VMMInformer.guide/INSTALLATION" @Next "VMMINFORMER" @Prev "INTRODUCTION" @Toc "Main" @{b}2. INSTALLATION@{ub} VMMInformer requires at least OS2.04 to run. VMMInformer also requires VMM 2.1 or greater to be installed to use all features of VMMInformer. Execute the following steps to install VMMInformer: - Copy @{"VMMInformer" Link "VMMINFORMER"} to your preferred path for utilities. - Copy VMMInformer.prefs to ENVARC: or generate your own preferences file. Now change the preferences file at will. I added three example preferences files to this archive in the prefs directory. Use these preferences files to get a first impression about the possibilities of VMMInformer. VMMInformer tries to read the file specified as argument in the command line first. If you didn't specify a prefs-file it will try to read ENV:VMMInformer.prefs and after that ENVARC:VMMInformer.prefs. See @{"Prefs-File syntax" Link "PREFS_SYNTAX"} for more details on that. @EndNode @Node "VMMINFORMER" "doc/VMMInformer.guide/VMMINFORMER" @Next "PREFS_SYNTAX" @Prev "INSTALLATION" @Toc "Main" @{b}3. VMMINFORMER@{ub} There is not much to explain about VMMInformer: TEMPLATE: VMMInformer [prefs-file] The VMMInformer display shows the strings with the selected variables mixed with the graphical display. If you have defined any graphics you can change the size of the window with the sizing-gadget, otherwise there is no sizing-gadget visible. See @{"Prefs-File syntax" Link "PREFS_SYNTAX"} for more details on that. @EndNode @Node "PREFS_SYNTAX" "doc/VMMInformer.guide/PREFS_SYNTAX" @Next "ERROR_LIST" @Prev "VMMINFORMER" @Toc "Main" @{b}4. PREFERENCES FILE - SYNTAX@{ub} @{b}IMPORTANT: DON'T@{ub} edit the first line in the preferences file. @{b}IMPORTANT:@{ub} The declaration blocks @{b}must@{ub} be defined in the following order: 1. "TASK/WINDOW/DEFAULT" 2. "VARIABLES" 3. "DISPLAY" @{b}IMPORTANT:@{ub} The syntax of the preferences file will be checked but not all errors will be recognized by the parser. @{b}Description of the preferences file syntax.@{ub} If you are not able to follow my descriptions please take a look at the example preferences files. Expecially "VMMInformer.crazy" will help you understanding the preferences file syntax. If you have problems with a special idea feel free to contact me and i try to help "//" starts a comment line : : : : : "TRUE" oder "FALSE" : Must be enclosed by quotes. I.e.: "test test test" The string must be entered in printf-style format. A maximum of 6 variables is allowed. In normal text strings only one variable is allowed. : One of the variables defined below (except d). : For the definition of functions you must use @{b}RPN-format@{ub}. You can use the following variables for your calculations: a) Variables defined in the VMStat-structure: - VMSize : Size of virtual memory - VMFree : Size of free virtual memory - Faults : Page faults up until now - PagesWritten : Pages written up until now - PagesRead : Pages read up until now - NumFrames : Actual no. of used frames - PagesUsed : Pages used on device - PageSize : Pagesize - TrapStructsFree: No. of free TrapStructs See "VMM.guide" for more details. b) 4 more variables concerning free memory and the time: - PUBLIC_FAST_Free: Free PUBLIC FAST memory - CHIP_Free : Free CHIP memory - CurrentSeconds : Current time (seconds) - CurrentMicros : Current time (micros) c) All key variables: Only SECONDS and MICROS may be of interest. (see below) d) Constants: i.e. 1, 45, 100000, ... (no negative values) e) All "ARRAY"-variables defined. f) All variables defined with "DEFINE" (functions). IMPORTANT: variables in e) and f) @{ub}must@{b} be defined before they are used!!! @{b}SYNTAX of functions:@{ub} IMPORTANT: Only ULONG variables are used for calculations. In complex calculations round off errors can occur. This doesn't mean your processor is faulty (INTEL outside). ALL variables are stored as ULONG integers. All functions MUST be entered in @{b}RPN-format@{ub}! The following operators are allowed: +, -, *, /, % Examples: i) Size of free virtual memory: - DEFINE VMUsed = VMSize VMFree - ii) No. of pagefaults during an update cycle: - ARRAYFaults = Faults - DEFINE Faults_per_update = ARRAYFaults(0) ARRAYFaults(-1) - iii) No. of faults during 1 second: - SECONDS = 20 - MICROS = 500000 - ARRAYFaults = Faults - DEFINE Update_Micros = SECONDS 1000000 * MICROS + - DEFINE Faults_per_update = ARRAYFaults(-1) ARRAYFaults(0) - - DEFINE Faults_per_second = Faults_per_update 1000000 * Update_Micros / --> START OF PREFERENCES FILE ********************************************************************** "BEGIN TASK/WINDOW/DEFAULT" starts the definition of the task and window specific variables. "VERSION = " Version of preferences file format. @{b}DON'T EDIT@{ub} "REVISION = " Revision of preferences file format. @{b}DON'T EDIT@{ub} "PRIORITY = " Priority of VMMInformer task (-128 bis 127). "LEFT = " Left edge of window. "TOP = " Right edge of window. "WIDTH = " Width of window. (The height depends on the font and the contents of the window.) "ZOOMED = " Open window zoomed (TRUE) or unzoomed (FALSE). "ZOOMED_LEFT = " Left edge of the zoomed window. "ZOOMED_TOP = " Right edge of the zoomed window. "BACKFILLCOLOR = " Background color (pen no.) "PANELCOLOR = " Panel color (pen no.) "TEXTCOLOR = " Text color (pen no.) "AUTOSCALE = " TRUE enables autoscale option. FALSE disables autoscale option. (see "EXCEED_COLOR"). "SHIFT = " Shift the graphic pixels to the left when the right window border is reached. "COLOR = " Default color for the graphical display. (pen no.) "EXCEED_COLOR = " Color which is used to mark that the value exceeds the graphical display. "SECONDS = " "MICROS = " Update the window every x seconds and y micros. "END" ends this definition. ********************************************************************** "BEGIN VARIABLES" starts the declaration of the variables. "ARRAY = " Declaration of a variable which can be used in calculations later. All values of this variable are stored in an array. (Up to the actual screen size). is the name of this variable. The name must follow directly after the keyword "ARRAY". I. e.: "ARRAY0", "ARRAYVMFree", "ARRAYStarTrek", ... Alphanumeric and numeric characters are allowed. You can access the last value stored in the array as follows: - ARRAY(-1) The value in parentheses can be between the current screen width - 1 and 0 (a negative number). "DEFINE = " This defines a new variable which will be recalculated every update cycle. is the name of this variable. After you have defined this variable you can access it in the following calculations. You can't access a variable which has not been defined before it is used for the first time. "END" ends this declaration. ********************************************************************** "BEGIN DISPLAY" starts the definition of strings and graphics. "@{"TITLE" Link "EXAMPLE_TITLE"} = [, [, ]...]" Window title "@{"ZOOMTITLE" Link "EXAMPLE_TITLE"} = [, [, ]...]" Window title in zoomed state. "@{"TEXT" Link "EXAMPLE_TEXT"} = [, ]" Strings defined in this way are displayed in the window in order of their definition. is the string to be displayed in the window and is the linked variable. is optional. "@{"GRAPHIC" Link "EXAMPLE_GRAPHIC"} = [, [], [[], [[], [[], [[]]]]]]" "var" = defines which variable is displayed as graphic. "height" = overrides the default height "pen" = overrides the default pen number. "autoscale" = overrides the default AUTOSCALE option. "scale_size" = value, in which distance the graphic is scaled "bars" = enables scalebars (TRUE) or disables them (FALSE) These variables are always only in reference to the actual defined graphic. "BAR = " color (pen no.) "END" ends this definition. ********************************************************************** --> END OF PREFERENCES FILE @EndNode @Node "ERROR_LIST" "doc/VMMInformer.guide/ERROR_LIST" @Next "KNOWN_BUGS" @Prev "PREFS_SYNTAX" @Toc "Main" @{b}5. ERROR LIST@{ub} ********************************************************************** Possible errors during preferences file parsing: Error no.: Description: 1 out of memory 2 couldn't open config file 3 SYNTAX error 4 undefined identifier or use out of BEGIN ... END 5 argument missing 6 ULONG argument missing: ULONG required 7 BOOLEAN argument missing: "TRUE" or "FALSE" required 8 quote mark missing 9 invalid argument 10 DAU, total memory failure in 2 minutes ;-) 11 "ARRAY" is not a valid variable name 12 invalid use of variable 13 variable name not found 14 invalid array offset 15 no graphic defined 16 wrong version of preferences file ********************************************************************** @EndNode @Node "KNOWN_BUGS" "doc/VMMInformer.guide/KNOWN_BUGS" @Next "HISTORY" @Prev "ERROR_LIST" @Toc "Main" @{b}6. KNOWN BUGS@{ub} If you find any bugs please mail them to me. If VMM isn't able to start correctly for some reason, VMMInformer may hang. This is not an error but is due to VMMInformer waiting for a response from VMM which isn't able to respond. @EndNode @Node "HISTORY" "doc/VMMInformer.guide/HISTORY" @Next "PLANS" @Prev "KNOWN_BUGS" @Toc "Main" @{b}7. HISTORY@{ub} Version 1.1 : - Changed the preferences file syntax (see convert.readme for more details) - Changed VMMInformer to work without VMM running. - Added two new variables for use with the graphical display a) "scale_size" b) "bars" - Text and graphical displays can be mixed together - Added a color configurable bar to seperate the output - Fixed a bug which caused VMMInformer to open the window always at the zoomed position - Fixed a bug which caused VMMInformer to clear the screen title while VMMInformer window is the active one - Minor bug fixes and changes Version 1.0 : First release @EndNode @Node "PLANS" "doc/VMMInformer.guide/PLANS" @Next "ACKNOWLEDGMENTS" @Prev "KNOWN_BUGS" @Toc "Main" @{b}8. FUTURE PLANS@{ub} - Integrate CPULoad in VMMInformer @EndNode @Node "ACKNOWLEDGMENTS" "doc/VMMInformer.guide/ACKNOWLEDGMENTS" @Prev "PLANS" @Toc "Main" @{b}9. ACKNOWLEDGMENTS@{ub} I would like to thank Martin Apel for providing me with ideas and helping me with problems. @EndNode @Node "EXAMPLE_GRAPHIC" @Toc "Main" Example about @{b}GRAPHIC@{ub} GRAPHIC = CPULoad, 30, 5, TRUE, 10, TRUE (Overrides default height, pen color and autoscale modus. Sets the scale_size to 10 and enables the scale bars) GRAPHIC = CHIP_Free,, 5 (overrides default pen color) Don't forget the commas if you only want to change the second or third attribute without touching the first or second one. @EndNode @Node "EXAMPLE_TEXT" @Toc "Main" Example about @{b}TEXT@{ub} TEXT = "Chip memory free:", CHIP_Free TEXT = "Fast memory free:", PUBLIC_FAST_Free @EndNode @Node "EXAMPLE_TITLE" @Toc "Main" Example about @{b}TITLE@{ub} TITLE = "VMMInformer %1.1ld.%1.1ld", VERSION, REVISION ZOOMTITLE = "VM: %5ld K, Chip: %4ld K, Fast: %5ld K %2.2ld:%2.2ld:%2.2ld", VMFreeK, CHIP_FreeK, PUBLIC_FAST_FreeK, Hours, Minutes, Seconds VMFreeK, CHIP_FreeK, PUBLIC_FAST_FreeK, Hours, Minutes, Seconds are user defined variables. @EndNode